# HistoryPanel（历史数据面板）

本章介绍 **HistoryPanel**：在已理解 [DataType](2.%20datatypes.md) 的前提下，如何把多标的、多指标、同一时间轴上的历史数据收拢为一块「面板」，并在策略研究、回测准备与可视化之间复用。阅读本章无需先读 [本地数据源 DataSource](3.%20datasource.md)，但若尚未向本地数据源填充数据，请先完成下载与配置后再使用 `get_history_data` 取数。

---

在上一章中，我们已经看到，`qteasy` 用 **DataType** 把「数据表里的原始列」抽象成策略与回测可以直接消费的**信息**。当这些信息需要在时间上与多只标的、多种数据类型（例如 OHLC、成交量、MACD 等）**对齐到同一套时间轴**上时，如果仍靠手工拼接多个 `DataFrame`，既容易出错，也不利于策略代码与可视化代码复用同一套数据结构。

**HistoryPanel（历史数据面板）** 正是为这一场景准备的容器：它在内部把数据组织为 **标的（shares）× 时间（index）× 数据类型（htypes）** 三维结构，让你可以用统一的接口做切片、筛选标的或指标，并在后续 **回测、策略逻辑或绘图** 中沿用同一份对象。对大多数用户来说，你并不需要关心面板在内部如何与本地数据源交互；通过熟悉的 **`get_history_data`** 等工作流拿到 `HistoryPanel` 之后，就可以把它当作「时间上对齐好的、可多标的、多指标的一块数据整体」来使用。

本章说明 HistoryPanel 的核心概念与常见用法；**下一章 [HistoryPanel 可视化](2.6.%20historypanel_visual.md)** 在此基础上介绍如何 **`hp.plot()`** 将同一块面板直接画成静态图或交互图。更底层的取数 API 分工，仅在 **[API 参考](../api/history_data.rst)** 中择要列出，以免与日常路径混淆。

---

## 核心概念：三维结构与 `shape`

HistoryPanel 在内存中对应一个三维 `numpy.ndarray`，三条轴依次为：

| 轴 | 含义 | 常用属性 |
| --- | --- | --- |
| 第 0 维 | 标的（证券代码等） | `shares`、`level_count` |
| 第 1 维 | 时间（历史日期或时刻） | `hdates`、`row_count` |
| 第 2 维 | 数据类型（如 `open`、`close`、`vol`） | `htypes`、`column_count` |

`shape` 返回 **`(标的数, 时间长度, 数据类型数)`**，与上面顺序一致。可以把它理解为：许多张「时间 × 指标」的二维表，在**标的**方向上再叠一层；同一面板内，各标的、各指标在时间上是对齐的。

与单标的宽表 `DataFrame`（行是时间、列是指标）相比，HistoryPanel 把 **多标的** 明确放在第 0 维，便于批量运算与按标的切片，而不必维护多层 `MultiIndex` 列。

*（示意图：可将「三维块」理解为 L 层标的 × R 行时间 × C 列指标；需要插图时可在后续版本补一张示意图。）*

## 如何获得 HistoryPanel

日常推荐路径是使用 **`qt.get_history_data(..., as_data_frame=False)`**：在本地数据源已有所需数据的前提下，一次指定 `htype_names`（与 DataType 命名一致，参见上一章）与 `shares`、时间范围或 `rows`，即可得到对齐后的 `HistoryPanel`。

默认情况下 `get_history_data` 的 `as_data_frame` 为 `True`，返回的是按标的分组的 **`dict[str, DataFrame]`**，适合快速查看单标的；**需要三维面板时，务必传入 `as_data_frame=False`**。完整参数、频率与复权等说明见 [历史数据 API](../api/history_data.rst)。

下面示例**不依赖网络**，用小型数组构造面板，便于理解 `shape` 与标签；实际工作中可改用 `get_history_data` 从本地数据源填充。

```python
import numpy as np
import pandas as pd
from qteasy import HistoryPanel

# 2 只标的、4 个交易日、3 种数据类型 → shape (2, 4, 3)
values = np.array(
    [
        [[1.0, 1.1, 100], [1.2, 1.3, 110], [1.15, 1.2, 105], [1.25, 1.28, 120]],
        [[10.0, 10.5, 200], [10.2, 10.8, 210], [10.1, 10.4, 205], [10.3, 10.9, 215]],
    ],
    dtype=float,
)
hp = HistoryPanel(
    values=values,
    levels=['000001.SZ', '000002.SZ'],
    rows=pd.date_range('2025-01-02', periods=4, freq='B'),
    columns=['open', 'high', 'vol'],
)
print(hp.shape)          # (2, 4, 3)
print(hp.shares)         # 标的列表
print(hp.htypes)         # 数据类型列表
```

若本地已有行情，可改为：

```python
import qteasy as qt

hp = qt.get_history_data(
    htype_names='open, high, low, close, vol',
    shares='000001.SZ',
    rows=60,
    as_data_frame=False,
)
print(hp.shape, hp.shares, hp.htypes)
```

## 基本操作：时间范围、标的与指标子集

下列方法在**不改变取数语义**的前提下，缩小你当前关心的范围；返回值仍是 `HistoryPanel`（空面板除外）。

- **按日期区间**：`segment(start_date, end_date)`，闭区间内的所有时间行；日期可与 `hdates` 中的粒度一致（日频、日内等）。
- **按行号区间**：`isegment(start_index, end_index)`，与 Python 切片类似，适用于按位置截取。
- **最近若干行**：`head(n)` / `tail(n)`。
- **按标的与/或指标名筛选**：`slice(shares='A, B', htypes='close, vol')`，字符串或列表均可。

单标的、多指标继续用 pandas 分析时，可用 **`to_share_frame(share)`** 得到该标的的 `DataFrame`（时间为索引，列为 `htypes`）。多标的导出还可参见 API 文档中的 **`to_df_dict`** 等说明。

`Operator` 与回测流程中，历史数据往往在策略运行调度阶段按组注入；具体参数与时间表配置见 **「创建并操作交易策略」** 相关章节。此处只需建立印象：**策略与可视化都可以围绕同一块 HistoryPanel（或其切片）展开**，从而减少「一份数据、多种形状」的重复整理。

## 指标与列扩展（`kline` 等）

在已有价格类 `htypes` 的基础上，可以通过 **`hp.kline`** 访问器调用均线、MACD、布林带等常见派生列。这类方法通常返回**新的** `HistoryPanel`：在第三维上**追加**指标列，**不原地修改**原对象，`shares` 与 `hdates` 与原面板一致。复权列名（如 `close|b`）在较新版本中会与 `kline`、`returns` 等解析逻辑对齐；若面板中同时存在裸名与复权列，建议阅读 [HistoryPanel API](../api/HistoryPanel.rst) 中的行为说明。

更完整的因子式示例（收益、波动率、`apply_ta` 等）可与教程 **[使用 HistoryPanel 操作和分析历史数据](../tutorials/2.5-historypanel-data-analysis.md)** 对照阅读。

## 小结与下一步

- HistoryPanel 提供 **`(标的 × 时间 × 数据类型)`** 统一容器，适合多标的、多指标且时间对齐的研究与回测准备。
- 日常用 **`get_history_data(..., as_data_frame=False)`** 获取面板；默认可先读上一章的 DataType 命名与 `get_dtype_map()`。
- 切片与子集：**`segment` / `isegment` / `head` / `tail` / `slice`**；导出单标的：**`to_share_frame`**。
- **下一章 [HistoryPanel 可视化](2.6.%20historypanel_visual.md)**：使用 **`hp.plot()`** 做静态或交互制图。
- 本地数据未就绪时，请先阅读 **[本地数据源 DataSource](3.%20datasource.md)** 与 **[数据拉取与渠道](10.%20data_channels.md)**。